2.6 Sparse trees

An important feature of Org-mode is the ability to construct sparse trees for selected information in an outline tree, so that the entire document is folded as much as possible, but the selected information is made visible along with the headline structure above it¹. Just try it out and you will see immediately how it works.

Org-mode contains several commands creating such trees, all these commands can be accessed through a dispatcher:

C-c /     (org-sparse-tree)

This prompts for an extra key to select a sparse-tree creating command.

C-c / r     (org-occur)

Occur. Prompts for a regexp and shows a sparse tree with all matches. If the match is in a headline, the headline is made visible. If the match is in the body of an entry, headline and body are made visible. In order to provide minimal context, also the full hierarchy of headlines above the match is shown, as well as the headline following the match. Each match is also highlighted; the highlights disappear when the buffer is changed by an editing command², or by pressing C-c C-c. When called with a C-u prefix argument, previous highlights are kept, so several calls to this command can be stacked.

For frequently used sparse trees of specific search strings, you can use the variable org-agenda-custom-commands to define fast keyboard access to specific sparse trees. These commands will then be accessible through the agenda dispatcher (see Agenda dispatcher). For example:

     (setq org-agenda-custom-commands
           '(("f" occur-tree "FIXME")))

will define the key C-c a f as a shortcut for creating a sparse tree matching the string ‘FIXME’.

The other sparse tree commands select headings based on TODO keywords, tags, or properties and will be discussed later in this manual.

To print a sparse tree, you can use the Emacs command ps-print-buffer-with-faces which does not print invisible parts of the document ³. Or you can use the command C-c C-e v to export only the visible part of the document and print the resulting file.